/* 哈希表实现。
 *
 * 此文件实现了带有插入/删除/替换/查找/
 * 获取随机元素操作的内存哈希表。哈希表会在需要时自动调整大小
 * 使用的表大小为2的幂，冲突通过链表方式处理。更多信息请参阅源代码... :)
 *
 * Copyright (c) 2006-Present, Redis Ltd.
 * All rights reserved.
 *
 * Licensed under your choice of (a) the Redis Source Available License 2.0
 * (RSALv2); or (b) the Server Side Public License v1 (SSPLv1); or (c) the
 * GNU Affero General Public License v3 (AGPLv3).
 */

#ifndef __DICT_H
#define __DICT_H

#include "mt19937-64.h"
#include <limits.h>
#include <stdint.h>
#include <stdlib.h>

#define DICT_OK 0
#define DICT_ERR 1

/* 哈希表参数 */
#define HASHTABLE_MIN_FILL        8      /* 哈希表最小填充率 12.5%(100/8) */

typedef struct dictEntry dictEntry; /* opaque */
typedef struct dict dict;
typedef size_t (*keyLenFunc)(dict *d, const void *key1);
typedef int (*keyCmpFuncWithLen)(dict *d, const void *key1, const size_t key1_len, const void *key2, const size_t key2_len);

typedef struct dictType {
    /* 回调函数 */
    uint64_t (*hashFunction)(const void *key);
    void *(*keyDup)(dict *d, const void *key);
    void *(*valDup)(dict *d, const void *obj);
    int (*keyCompare)(dict *d, const void *key1, const void *key2);
    void (*keyDestructor)(dict *d, void *key);
    void (*valDestructor)(dict *d, void *obj);
    int (*resizeAllowed)(size_t moreMem, double usedRatio);
    /* 在字典初始化/重哈希开始时调用（旧的和新的哈希表已经创建） */
    void (*rehashingStarted)(dict *d);
    /* 在字典初始化/重哈希结束时调用，所有条目已从旧哈希表移动到新哈希表。两个哈希表仍然存在
     * 并在此回调后被清理。 */
    void (*rehashingCompleted)(dict *d);
    /* 允许字典携带额外的调用者定义的元数据。
     * 当字典被分配时，额外的内存被初始化为0。 */
    size_t (*dictMetadataBytes)(dict *d);

    /* 数据 */
    void *userdata;

    /* 标志 */
    /* 如果设置了'no_value'标志，表示不使用值，即字典是一个集合。当设置此标志时，无法访问
     * dictEntry的值，也无法使用dictSetKey()。它
     * 启用了一种优化，如果是桶中唯一的键，可以直接存储键而不需要在中间分配
     * dictEntry。 */
    unsigned int no_value:1;
    /* 此标志对于`no_value`优化是必需的，因为优化
     * 重用LSB位作为元数据 */ 
    unsigned int keys_are_odd:1;
    /* TODO：添加'keys_are_even'标志，如果设置了该标志，则使用类似的优化。 */

    /* 如果设置，则确保整个哈希表一次性重新哈希。 */
    unsigned int force_full_rehash:1;

    /* 有时我们希望能够以特定方式在哈希函数内部存储键，
     * 并以其他方式查找它而不需要任何形式的转换。例如，键可能存储为一个结构
     * 同时表示其他东西，但查找仅通过指向
     * 以空字符结尾的字符串的指针进行。通过可选地提供额外的哈希/比较函数，
     * 字典支持这种用法。在这种情况下，我们会有一个hashFunction()，它将
     * 期望一个以空字符结尾的C字符串，而storedHashFunction()将
     * 期望结构。同样，这两个比较函数将
     * 以不同的方式工作。keyCompare()将把第一个参数视为指向
     * C字符串的指针，另一个视为结构（这样我们可以直接使用C字符串查找
     * 结构键）。而storedKeyCompare()将
     * 检查两个指向结构形式键的指针是否相同。
     *
     * 然而，以键为参数（void *key）的字典函数无法
     * 知道它是查找键还是存储键。要表示您
     * 打算使用存储键类型的键，因此使用
     * 存储键的专用比较和哈希函数，方法是在使用任何以
     * 键为参数的字典函数之前调用dictUseStoredKeyApi(1)，
     * 然后在完成后再次调用dictUseStoredKeyApi(0)。
     *
     * 如果不希望支持此功能，请将这两个函数都设置为NULL。 */
    uint64_t (*storedHashFunction)(const void *key);
    int (*storedKeyCompare)(dict *d, const void *key1, const void *key2);

    /* 字典被销毁时调用的可选回调。 */
    void (*onDictRelease)(dict *d);

    /* 可选的keylen用于避免重复计算键的长度。 */
    keyLenFunc keyLen;
    keyCmpFuncWithLen keyCompareWithLen;
} dictType;

#define DICTHT_SIZE(exp) ((exp) == -1 ? 0 : (unsigned long)1<<(exp))
#define DICTHT_SIZE_MASK(exp) ((exp) == -1 ? 0 : (DICTHT_SIZE(exp))-1)

struct dict {
    dictType *type;

    dictEntry **ht_table[2];
    unsigned long ht_used[2];

    long rehashidx; /* 如果rehashidx == -1表示不在进行重哈希 */

    /* 将小变量放在末尾以获得最佳（最小）的结构体填充 */
    unsigned pauserehash : 15; /* 如果>0表示重哈希被暂停 */

    unsigned useStoredKeyApi : 1; /* 请参阅上面storedHashFunction的注释 */
    signed char ht_size_exp[2]; /* 大小的指数。(size = 1<<exp) */
    int16_t pauseAutoResize;  /* 如果>0表示禁止自动调整大小(<0表示编码错误) */
    void *metadata[];
};

/* 如果safe设置为1，则这是一个安全迭代器，意味着即使在迭代过程中
 * 也可以对字典调用dictAdd、dictFind和其他函数。否则，它是一个不安全的迭代器，
 * 在迭代过程中只能调用dictNext()。 */
typedef struct dictIterator {
    dict *d;
    long index;
    int table, safe;
    dictEntry *entry, *nextEntry;
    /* 用于检测误用的不安全迭代器指纹。 */
    unsigned long long fingerprint;
} dictIterator;

typedef struct dictStats {
    int htidx;
    unsigned long buckets;
    unsigned long maxChainLen;
    unsigned long totalChainLen;
    unsigned long htSize;
    unsigned long htUsed;
    unsigned long *clvector;
} dictStats;

typedef void (dictScanFunction)(void *privdata, const dictEntry *de);
typedef void *(dictDefragAllocFunction)(void *ptr);
typedef struct {
    dictDefragAllocFunction *defragAlloc; /* 用于条目等 */
    dictDefragAllocFunction *defragKey;   /* 碎片整理-重新分配键（可选） */
    dictDefragAllocFunction *defragVal;   /* 碎片整理-重新分配值（可选） */
} dictDefragFunctions;

/* 这是每个哈希表的初始大小 */
#define DICT_HT_INITIAL_EXP      2
#define DICT_HT_INITIAL_SIZE     (1<<(DICT_HT_INITIAL_EXP))

/* ------------------------------- Macros ------------------------------------*/
#define dictFreeVal(d, entry) do {                     \
    if ((d)->type->valDestructor)                      \
        (d)->type->valDestructor((d), dictGetVal(entry)); \
   } while(0)

#define dictFreeKey(d, entry) \
    if ((d)->type->keyDestructor) \
        (d)->type->keyDestructor((d), dictGetKey(entry))

#define dictCompareKeys(d, key1, key2) \
    (((d)->type->keyCompare) ? \
        (d)->type->keyCompare((d), key1, key2) : \
        (key1) == (key2))

#define dictMetadata(d) (&(d)->metadata)
#define dictMetadataSize(d) ((d)->type->dictMetadataBytes \
                             ? (d)->type->dictMetadataBytes(d) : 0)

#define dictBuckets(d) (DICTHT_SIZE((d)->ht_size_exp[0])+DICTHT_SIZE((d)->ht_size_exp[1]))
#define dictSize(d) ((d)->ht_used[0]+(d)->ht_used[1])
#define dictIsEmpty(d) ((d)->ht_used[0] == 0 && (d)->ht_used[1] == 0)
#define dictIsRehashing(d) ((d)->rehashidx != -1)
#define dictPauseRehashing(d) ((d)->pauserehash++)
#define dictResumeRehashing(d) ((d)->pauserehash--)
#define dictIsRehashingPaused(d) ((d)->pauserehash > 0)
#define dictPauseAutoResize(d) ((d)->pauseAutoResize++)
#define dictResumeAutoResize(d) ((d)->pauseAutoResize--)
#define dictUseStoredKeyApi(d, flag) ((d)->useStoredKeyApi = (flag))

/* If our unsigned long type can store a 64 bit number, use a 64 bit PRNG. */
#if ULONG_MAX >= 0xffffffffffffffff
#define randomULong() ((unsigned long) genrand64_int64())
#else
#define randomULong() random()
#endif

typedef enum {
    DICT_RESIZE_ENABLE,  // 允许调整大小
    DICT_RESIZE_AVOID,   // 避免调整大小
    DICT_RESIZE_FORBID,  // 禁止调整大小
} dictResizeEnable;

/* API */
dict *dictCreate(dictType *type);
void dictTypeAddMeta(dict **d, dictType *typeWithMeta);
int dictExpand(dict *d, unsigned long size);
int dictTryExpand(dict *d, unsigned long size);
int dictShrink(dict *d, unsigned long size);
int dictAdd(dict *d, void *key, void *val);
dictEntry *dictAddRaw(dict *d, void *key, dictEntry **existing);
dictEntry *dictAddNonExistsByHash(dict *d, void *key, const uint64_t hash);
void *dictFindPositionForInsert(dict *d, const void *key, dictEntry **existing);
dictEntry *dictInsertAtPosition(dict *d, void *key, void *position);
dictEntry *dictAddOrFind(dict *d, void *key);
int dictReplace(dict *d, void *key, void *val);
int dictDelete(dict *d, const void *key);
dictEntry *dictUnlink(dict *d, const void *key);
void dictFreeUnlinkedEntry(dict *d, dictEntry *he);
dictEntry *dictTwoPhaseUnlinkFind(dict *d, const void *key, dictEntry ***plink, int *table_index);
void dictTwoPhaseUnlinkFree(dict *d, dictEntry *he, dictEntry **plink, int table_index);
void dictRelease(dict *d);
dictEntry * dictFind(dict *d, const void *key);
dictEntry *dictFindByHash(dict *d, const void *key, const uint64_t hash);
dictEntry *dictFindByHashAndPtr(dict *d, const void *oldptr, const uint64_t hash);
void *dictFetchValue(dict *d, const void *key);
int dictShrinkIfNeeded(dict *d);
int dictExpandIfNeeded(dict *d);
void dictSetKey(dict *d, dictEntry* de, void *key);
void dictSetVal(dict *d, dictEntry *de, void *val);
void dictSetSignedIntegerVal(dictEntry *de, int64_t val);
void dictSetUnsignedIntegerVal(dictEntry *de, uint64_t val);
void dictSetDoubleVal(dictEntry *de, double val);
int64_t dictIncrSignedIntegerVal(dictEntry *de, int64_t val);
uint64_t dictIncrUnsignedIntegerVal(dictEntry *de, uint64_t val);
double dictIncrDoubleVal(dictEntry *de, double val);
void *dictEntryMetadata(dictEntry *de);
void *dictGetKey(const dictEntry *de);
void *dictGetVal(const dictEntry *de);
int64_t dictGetSignedIntegerVal(const dictEntry *de);
uint64_t dictGetUnsignedIntegerVal(const dictEntry *de);
double dictGetDoubleVal(const dictEntry *de);
double *dictGetDoubleValPtr(dictEntry *de);
size_t dictMemUsage(const dict *d);
size_t dictEntryMemUsage(void);
dictIterator *dictGetIterator(dict *d);
dictIterator *dictGetSafeIterator(dict *d);
void dictInitIterator(dictIterator *iter, dict *d);
void dictInitSafeIterator(dictIterator *iter, dict *d);
void dictResetIterator(dictIterator *iter);
dictEntry *dictNext(dictIterator *iter);
void dictReleaseIterator(dictIterator *iter);
dictEntry *dictGetRandomKey(dict *d);
dictEntry *dictGetFairRandomKey(dict *d);
unsigned int dictGetSomeKeys(dict *d, dictEntry **des, unsigned int count);
void dictGetStats(char *buf, size_t bufsize, dict *d, int full);
uint64_t dictGenHashFunction(const void *key, size_t len);
uint64_t dictGenCaseHashFunction(const unsigned char *buf, size_t len);
void dictEmpty(dict *d, void(callback)(dict*));
void dictSetResizeEnabled(dictResizeEnable enable);
int dictRehash(dict *d, int n);
int dictRehashMicroseconds(dict *d, uint64_t us);
void dictSetHashFunctionSeed(uint8_t *seed);
uint8_t *dictGetHashFunctionSeed(void);
unsigned long dictScan(dict *d, unsigned long v, dictScanFunction *fn, void *privdata);
unsigned long dictScanDefrag(dict *d, unsigned long v, dictScanFunction *fn, dictDefragFunctions *defragfns, void *privdata);
uint64_t dictGetHash(dict *d, const void *key);
void dictRehashingInfo(dict *d, unsigned long long *from_size, unsigned long long *to_size);

size_t dictGetStatsMsg(char *buf, size_t bufsize, dictStats *stats, int full);
dictStats* dictGetStatsHt(dict *d, int htidx, int full);
void dictCombineStats(dictStats *from, dictStats *into);
void dictFreeStats(dictStats *stats);

#define dictForEach(d, ty, m, ...) do { \n    dictIterator *di = dictGetIterator(d); \n    dictEntry *de; \n    while ((de = dictNext(di)) != NULL) { \n        ty *m = dictGetVal(de); \n        do { \n            __VA_ARGS__ \n        } while(0); \n    } \n    dictReleaseIterator(di); \n} while(0); /* 遍历字典中的所有元素 */

#ifdef REDIS_TEST
int dictTest(int argc, char *argv[], int flags);
#endif

#endif /* __DICT_H */
